---
title: "Filtering Memories"
description: "Filter memories by container tags and metadata using SQL-based filtering"
---

Filter memories using container tags and metadata. The filtering system uses SQL query construction, so you need to structure your filters like database queries.

## Filter by Container Tags

Container tags use exact array matching - memories must have the exact same tags in the same order.

<Tabs>
  <Tab title="TypeScript">
    ```typescript
    // Single tag - matches memories with exactly ["user_123"]
    const userMemories = await client.memories.list({
      containerTags: ["user_123"]
    });

    // Multiple tags - matches memories with exactly ["user_123", "project_ai"]
    const projectMemories = await client.memories.list({
      containerTags: ["user_123", "project_ai"]
    });
    ```
  </Tab>
  <Tab title="Python">
    ```python
    # Single tag
    user_memories = client.memories.list(container_tags=["user_123"])

    # Multiple tags (exact match)
    project_memories = client.memories.list(
        container_tags=["user_123", "project_ai"]
    )
    ```
  </Tab>
  <Tab title="cURL">
    ```bash
    # Single tag
    curl -X POST "https://api.supermemory.ai/v3/documents/list" \
      -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"containerTags": ["user_123"]}'

    # Multiple tags
    curl -X POST "https://api.supermemory.ai/v3/documents/list" \
      -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"containerTags": ["user_123", "project_ai"]}'
    ```
  </Tab>
</Tabs>

## Metadata Filtering with SQL Logic

The `filters` parameter allows filtering by metadata fields using SQL-like query structures. Since we use SQL query construction in the backend, you need to structure your filters like database queries with explicit AND/OR logic.

### Why This Structure?

In SQL databases, `AND` has higher precedence than `OR`. Without explicit grouping, a query like:
```
category = 'programming' OR framework = 'react' AND difficulty = 'advanced'
```

Is interpreted as:
```
category = 'programming' OR (framework = 'react' AND difficulty = 'advanced')
```

The JSON structure forces explicit grouping to prevent unexpected results.

<Info>
**Filter Structure Rules:**
- Always wrap conditions in `AND` or `OR` arrays (even single conditions)
- Use `JSON.stringify()` to convert the filter object to a string
- Each condition needs `key`, `value`, and `negate` properties
- `negate: false` for normal matching, `negate: true` for exclusion
</Info>

### Simple Metadata Filter

<Tabs>
  <Tab title="TypeScript">
    ```typescript
    // Filter by single metadata field
    const programmingMemories = await client.memories.list({
      filters: JSON.stringify({
        AND: [
          { key: "category", value: "programming", negate: false }
        ]
      })
    });
    ```
  </Tab>
  <Tab title="Python">
    ```python
    import json

    # Filter by single metadata field
    programming_memories = client.memories.list(
        filters=json.dumps({
            "AND": [
                {"key": "category", "value": "programming", "negate": False}
            ]
        })
    )
    ```
  </Tab>
  <Tab title="cURL">
    ```bash
    curl -X POST "https://api.supermemory.ai/v3/documents/list" \
      -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "filters": "{\"AND\":[{\"key\":\"category\",\"value\":\"programming\",\"negate\":false}]}"
      }'
    ```
  </Tab>
</Tabs>

### Multiple Conditions (AND Logic)

<Tabs>
  <Tab title="TypeScript">
    ```typescript
    // All conditions must match
    const reactTutorials = await client.memories.list({
      filters: JSON.stringify({
        AND: [
          { key: "category", value: "tutorial", negate: false },
          { key: "framework", value: "react", negate: false },
          { key: "difficulty", value: "beginner", negate: false }
        ]
      })
    });
    ```
  </Tab>
  <Tab title="Python">
    ```python
    # All conditions must match
    react_tutorials = client.memories.list(
        filters=json.dumps({
            "AND": [
                {"key": "category", "value": "tutorial", "negate": False},
                {"key": "framework", "value": "react", "negate": False},
                {"key": "difficulty", "value": "beginner", "negate": False}
            ]
        })
    )
    ```
  </Tab>
  <Tab title="cURL">
    ```bash
    curl -X POST "https://api.supermemory.ai/v3/documents/list" \
      -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "filters": "{\"AND\":[{\"key\":\"category\",\"value\":\"tutorial\",\"negate\":false},{\"key\":\"framework\",\"value\":\"react\",\"negate\":false}]}"
      }'
    ```
  </Tab>
</Tabs>

### Alternative Conditions (OR Logic)

<Tabs>
  <Tab title="TypeScript">
    ```typescript
    // Any condition can match
    const frontendMemories = await client.memories.list({
      filters: JSON.stringify({
        OR: [
          { key: "framework", value: "react", negate: false },
          { key: "framework", value: "vue", negate: false },
          { key: "framework", value: "angular", negate: false }
        ]
      })
    });
    ```
  </Tab>
  <Tab title="Python">
    ```python
    # Any condition can match
    frontend_memories = client.memories.list(
        filters=json.dumps({
            "OR": [
                {"key": "framework", "value": "react", "negate": False},
                {"key": "framework", "value": "vue", "negate": False},
                {"key": "framework", "value": "angular", "negate": False}
            ]
        })
    )
    ```
  </Tab>
  <Tab title="cURL">
    ```bash
    curl -X POST "https://api.supermemory.ai/v3/documents/list" \
      -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "filters": "{\"OR\":[{\"key\":\"framework\",\"value\":\"react\",\"negate\":false},{\"key\":\"framework\",\"value\":\"vue\",\"negate\":false}]}"
      }'
    ```
  </Tab>
</Tabs>

### Complex Nested Logic

<Tabs>
  <Tab title="TypeScript">
    ```typescript
    // Complex logic: programming AND (react OR advanced difficulty)
    const advancedContent = await client.memories.list({
      filters: JSON.stringify({
        AND: [
          { key: "category", value: "programming", negate: false },
          {
            OR: [
              { key: "framework", value: "react", negate: false },
              { key: "difficulty", value: "advanced", negate: false }
            ]
          }
        ]
      })
    });
    ```
  </Tab>
  <Tab title="Python">
    ```python
    # Complex logic: programming AND (react OR advanced difficulty)
    advanced_content = client.memories.list(
        filters=json.dumps({
            "AND": [
                {"key": "category", "value": "programming", "negate": False},
                {
                    "OR": [
                        {"key": "framework", "value": "react", "negate": False},
                        {"key": "difficulty", "value": "advanced", "negate": False}
                    ]
                }
            ]
        })
    )
    ```
  </Tab>
  <Tab title="cURL">
    ```bash
    curl -X POST "https://api.supermemory.ai/v3/documents/list" \
      -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "filters": "{\"AND\":[{\"key\":\"category\",\"value\":\"programming\",\"negate\":false},{\"OR\":[{\"key\":\"framework\",\"value\":\"react\",\"negate\":false},{\"key\":\"difficulty\",\"value\":\"advanced\",\"negate\":false}]}]}"
      }'
    ```
  </Tab>
</Tabs>

## Array Contains Filtering

Filter memories that contain specific values in array fields like participants, tags, or team members.

### Basic Array Contains

<Tabs>
  <Tab title="TypeScript">
    ```typescript
    // Find memories where john.doe participated
    const meetingMemories = await client.memories.list({
      filters: JSON.stringify({
        AND: [
          {
            key: "participants",
            value: "john.doe",
            filterType: "array_contains",
            negate: false
          }
        ]
      })
    });
    ```
  </Tab>
  <Tab title="Python">
    ```python
    # Find memories where john.doe participated
    meeting_memories = client.memories.list(
        filters=json.dumps({
            "AND": [
                {
                    "key": "participants",
                    "value": "john.doe",
                    "filterType": "array_contains",
                    "negate": False
                }
            ]
        })
    )
    ```
  </Tab>
  <Tab title="cURL">
    ```bash
    curl -X POST "https://api.supermemory.ai/v3/documents/list" \
      -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "filters": "{\"AND\":[{\"key\":\"participants\",\"value\":\"john.doe\",\"filterType\":\"array_contains\",\"negate\":false}]}"
      }'
    ```
  </Tab>
</Tabs>

### Array Contains with Exclusion

<Tabs>
  <Tab title="TypeScript">
    ```typescript
    // Find memories that don't include a specific team member
    const filteredMemories = await client.memories.list({
      filters: JSON.stringify({
        AND: [
          {
            key: "reviewers",
            value: "external.consultant",
            filterType: "array_contains",
            negate: true  // Exclude memories with external consultants
          },
          {
            key: "project_tags",
            value: "internal-only",
            filterType: "array_contains",
            negate: false
          }
        ]
      })
    });
    ```
  </Tab>
  <Tab title="Python">
    ```python
    # Find memories that don't include a specific team member
    filtered_memories = client.memories.list(
        filters=json.dumps({
            "AND": [
                {
                    "key": "reviewers",
                    "value": "external.consultant",
                    "filterType": "array_contains",
                    "negate": True  # Exclude memories with external consultants
                },
                {
                    "key": "project_tags",
                    "value": "internal-only",
                    "filterType": "array_contains",
                    "negate": False
                }
            ]
        })
    )
    ```
  </Tab>
  <Tab title="cURL">
    ```bash
    curl -X POST "https://api.supermemory.ai/v3/documents/list" \
      -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "filters": "{\"AND\":[{\"key\":\"reviewers\",\"value\":\"external.consultant\",\"filterType\":\"array_contains\",\"negate\":true},{\"key\":\"project_tags\",\"value\":\"internal-only\",\"filterType\":\"array_contains\",\"negate\":false}]}"
      }'
    ```
  </Tab>
</Tabs>

### Multiple Array Contains (OR Logic)

<Tabs>
  <Tab title="TypeScript">
    ```typescript
    // Find memories involving any of several team leads
    const leadershipMemories = await client.memories.list({
      filters: JSON.stringify({
        OR: [
          {
            key: "attendees",
            value: "engineering.lead",
            filterType: "array_contains"
          },
          {
            key: "attendees",
            value: "product.lead",
            filterType: "array_contains"
          },
          {
            key: "attendees",
            value: "design.lead",
            filterType: "array_contains"
          }
        ]
      }),
      sort: "updatedAt",
      order: "desc"
    });
    ```
  </Tab>
  <Tab title="Python">
    ```python
    # Find memories involving any of several team leads
    leadership_memories = client.memories.list(
        filters=json.dumps({
            "OR": [
                {
                    "key": "attendees",
                    "value": "engineering.lead",
                    "filterType": "array_contains"
                },
                {
                    "key": "attendees",
                    "value": "product.lead",
                    "filterType": "array_contains"
                },
                {
                    "key": "attendees",
                    "value": "design.lead",
                    "filterType": "array_contains"
                }
            ]
        }),
        sort="updatedAt",
        order="desc"
    )
    ```
  </Tab>
  <Tab title="cURL">
    ```bash
    curl -X POST "https://api.supermemory.ai/v3/documents/list" \
      -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "filters": "{\"OR\":[{\"key\":\"attendees\",\"value\":\"engineering.lead\",\"filterType\":\"array_contains\"},{\"key\":\"attendees\",\"value\":\"product.lead\",\"filterType\":\"array_contains\"},{\"key\":\"attendees\",\"value\":\"design.lead\",\"filterType\":\"array_contains\"}]}",
        "sort": "updatedAt",
        "order": "desc"
      }'
    ```
  </Tab>
</Tabs>

## Combined Container Tags + Metadata Filtering

<Tabs>
  <Tab title="TypeScript">
    ```typescript
    const filteredMemories = await client.memories.list({
      containerTags: ["user_123"],
      filters: JSON.stringify({
        AND: [
          { key: "category", value: "tutorial", negate: false },
          { key: "framework", value: "react", negate: false }
        ]
      }),
      sort: "updatedAt",
      order: "desc",
      limit: 50
    });
    ```
  </Tab>
  <Tab title="Python">
    ```python
    filtered_memories = client.memories.list(
        container_tags=["user_123"],
        filters=json.dumps({
            "AND": [
                {"key": "category", "value": "tutorial", "negate": False},
                {"key": "framework", "value": "react", "negate": False}
            ]
        }),
        sort="updatedAt",
        order="desc",
        limit=50
    )
    ```
  </Tab>
  <Tab title="cURL">
    ```bash
    curl -X POST "https://api.supermemory.ai/v3/documents/list" \
      -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "containerTags": ["user_123"],
        "filters": "{\"AND\":[{\"key\":\"category\",\"value\":\"tutorial\",\"negate\":false},{\"key\":\"framework\",\"value\":\"react\",\"negate\":false}]}",
        "sort": "updatedAt",
        "order": "desc",
        "limit": 50
      }'
    ```
  </Tab>
</Tabs>

<Warning>
**Common Mistakes:**
- Using bare condition objects: `{"key": "category", "value": "programming"}`
- Forgetting JSON.stringify: passing objects instead of strings
- Missing negate property: always include `"negate": false` or `"negate": true`
</Warning>

<Note>
**Container Tags vs Metadata Filtering:**
- Container tags: Exact array matching for organizational grouping
- Metadata filters: SQL-like queries on custom metadata fields with complex logic
- Both can be combined for powerful filtering capabilities
</Note>
